v0.31.0

aws.Config Retryer member

If your application sets the Config.Retryer member the application will need
to be updated to set a function that returns an aws.Retryer. In addition, if
your application used the config.WithRetryer helper a function that returns
an aws.Retryer needs to be used.

If your application used the retry.Retryer type, update to using the
aws.Retryer type instead.

API Client enum value names

If your application used the enum values in the API Client's types package between v0.31.0 and the latest version of the client module you may need to update the naming of the enum value. The enum value name casing were updated to camel case instead lowercased.

v0.30.0

smithy-go module relocation

If your application uses smithy-go utilities for request pipeline your application will need to be updated to refer to the new import path of github.com/aws/smithy-go. If you application did not use smithy-go utilities directly, your application will update automatically.

EC2 IMDS module relocation

If your application used the ec2imds module, it has been relocated to feature/ec2/imds. Your application will need to update to the new import path, github.com/aws/aws-sdk-go-v2/feature/ec2/imds.

CredentialsCache Constructor and ExpiryWindow Options

The aws#CredentialsCache type was updated, and a new constructor function, NewCredentialsCache was added. This function needs to be used to initialize the CredentialCache. The constructor also has function options to specify additional configuration, e.g. ExpiryWindow and Jitter.

If your application was specifying the ExpiryWindow with the credentials/stscreds#AssumeRoleOptions, credentials/stscreds#WebIdentityRoleOptions, credentials/processcreds#Options, or credentials/ec2rolecrds#Options types the ExpiryWindow option will need to specified on the CredentialsCache constructor instead.

AWS Sigv4 Signer Refactor

The aws/signer/v4 package's Signer.SignHTTP and Signer.PresignHTTP methods were updated to take functional options. If your application provided a custom implementation for API client's HTTPSignerV4 or HTTPPresignerV4 interfaces, that implementation will need to be updated for the new function signature.

Configuration Loading

The config#LoadDefaultConfig function has been updated to require a context.Context as the first parameter, with additional optional function options as variadic additional arguments. Your application will need to update its usage of LoadDefaultConfig to pass in context.Context as the first parameter. If your application used the With... helpers those should continue to work without issue.

The v2 SDK corrects its behavior to be inline with the AWS CLI and other AWS SDKs. Refer to https://docs.aws.amazon.com/credref/latest/refdocs/overview.html for more information how to use the shared config and credentials files.

v0.29.0

aws.BuildableHTTPClient move

The aws's BuildableHTTPClient HTTP client implementation was moved to aws/transport/http as BuildableClient. If your application used the aws.BuildableHTTPClient type, update it to use the BuildableClient in the aws/transport/http package.

Slice and Map API member types

This release includes several code generation updates for API client's slice map members. Using API modeling metadata the Slice and map members are now generated as value types instead of pointer types. For your application this means that for these types, the SDK no longer will have pointer member types, and have value member types.

To migrate to this change you'll need to remove the pointer handling for slice and map members, and instead use value type handling of the member values.

Boolean and Number API member types

Similar to the slice and map API member types being generated as value, the SDK's code generation now has metadata where the SDK can generate boolean and number members as value type instead of pointer types.

To migrate to this change you'll need to remove the pointer handling for numbers and boolean member types, and instead use value handling.

v0.28.0

• API Clients ResolverOptions type renamed to EndpointResolverOptions

v0.27.0

Configuration

The config module's exported types were trimmed down to add clarity and reduce confusion. Additional changes to the config module' helpers.

• Refactored WithCredentialsProvider, WithHTTPClient, and WithEndpointResolver to functions instead of structs.
• Removed MFATokenFuncProvider, use AssumeRoleCredentialOptionsProvider for setting options for stscreds.AssumeRoleOptions.
• Renamed WithWebIdentityCredentialProviderOptions to WithWebIdentityRoleCredentialOptions
• Renamed AssumeRoleCredentialProviderOptions to AssumeRoleCredentialOptionsProvider
• Renamed EndpointResolverFuncProvider to EndpointResolverProvider

API Client

• API Client Options type getter methods have been removed. Use the struct members instead.
• The error returned by API Client operations was renamed from smithy.OperationError to smithy.OperationInvokeError.

v0.26.0

Configuration

The config module's exported types were trimmed down to add clarity and reduce confusion. Additional changes to the config module' helpers.

• Refactored WithCredentialsProvider, WithHTTPClient, and WithEndpointResolver to functions instead of structs.
• Removed MFATokenFuncProvider, use AssumeRoleCredentialOptionsProvider for setting options for stscreds.AssumeRoleOptions.
• Renamed WithWebIdentityCredentialProviderOptions to WithWebIdentityRoleCredentialOptions
• Renamed AssumeRoleCredentialProviderOptions to AssumeRoleCredentialOptionsProvider
• Renamed EndpointResolverFuncProvider to EndpointResolverProvider

API Client

• API Client Options type getter methods have been removed. Use the struct members instead.
• The error returned by API Client operations was renamed from smithy.OperationError to smithy.OperationInvokeError.

v0.25.0

Design changes

The v2 preview SDK v0.25.0 release represents a significant stepping stone bringing the v2 SDK closer to its target design and usability. This release includes significant breaking changes to the v2 preview SDK. The updates in the v0.25.0 release focus on refactoring and modularization of the SDK’s API clients to use the new client design, updated request pipeline (aka middleware), refactored credential providers, and configuration loading packages.

We've also bumped the minimum supported Go version with this release. Starting with v0.25.0 the SDK requires a minimum version of Go v1.15.

As a part of the refactoring done to v2 preview SDK some components have not been included in this update. The following is a non exhaustive list of features that are not available.

• API Paginators - #​439
• API Waiters - #​442
• Presign URL - #​794
• Amazon S3 Upload and Download manager - #​802
• Amazon DynamoDB's AttributeValue marshaler, and Expression package - #​790
• Debug Logging - #​594

We expect additional breaking changes to the v2 preview SDK in the coming releases. We expect these changes to focus on organizational, naming, and hardening the SDK's design for future feature capabilities after it is released for general availability.

Relocated Packages

In this release packages within the SDK were relocated, and in some cases those packages were converted to Go modules. The following is a list of packages have were relocated.

• github.com/aws/aws-sdk-go-v2/aws/external => github.com/aws/aws-sdk-go-v2/config module
• github.com/aws/aws-sdk-go-v2/aws/ec2metadata => github.com/aws/aws-sdk-go-v2/ec2imds module

The github.com/aws/aws-sdk-go-v2/credentials module contains refactored credentials providers.

• github.com/aws/aws-sdk-go-v2/ec2rolecreds => github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds
• github.com/aws/aws-sdk-go-v2/endpointcreds => github.com/aws/aws-sdk-go-v2/credentials/endpointcreds
• github.com/aws/aws-sdk-go-v2/processcreds => github.com/aws/aws-sdk-go-v2/credentials/processcreds
• github.com/aws/aws-sdk-go-v2/stscreds => github.com/aws/aws-sdk-go-v2/credentials/stscreds

Modularization

New modules were added to the v2 preview SDK to allow the components to be versioned independently from each other. This allows your application to depend on specific versions of an API client module, and take discrete updates from the SDK core and other API client modules as desired.

• github.com/aws/aws-sdk-go-v2/config
• github.com/aws/aws-sdk-go-v2/credentials
• Module for each API client, e.g. github.com/aws/aws-sdk-go-v2/service/s3

API Clients

The following is a list of the major changes to the API client modules

• Removed paginators: we plan to add these back once they are implemented to integrate with the SDK's new API client design.
• Removed waiters: we need to further investigate how the V2 SDK should expose waiters, and how their behavior should be modeled.
• API Clients are now Go modules. When migrating to the v2 preview SDK v0.25.0, you'll need to add the API client's module to your application's go.mod file.
• API parameter nested types have been moved to a types package within the API client's module, e.g. github.com/aws/aws-sdk-go-v2/service/s3/types These types were moved to improve documentation and discovery of the API client, operation, and input/output types. For example Amazon S3's ListObject's operation ListObjectOutput.Contents input parameter is a slice of types.Object.
• The client operation method has been renamed, removing the Request suffix. The method now invokes the operation instead of constructing a request, which needed to be invoked separately. The operation methods were also expanded to include functional options for providing operation specific configuration, such as modifying the request pipeline.

result, err := client.Scan(context.TODO(), &dynamodb.ScanInput{
    TableName: aws.String("exampleTable"),
}, func(o *Options) {
    // Limit operation calls to only 1 attempt.
    o.Retryer = retry.AddWithMaxAttempts(o.Retryer, 1)
})

Configuration

In addition to the github.com/aws/aws-sdk-go-v2/aws/external package being made a module at github.com/aws/aws-sdk-go-v2/config, the LoadDefaultAWSConfig function was renamed to LoadDefaultConfig.

The github.com/aws/aws-sdk-go-v2/aws/defaults package has been removed. Its components have been migrated to the github.com/aws/aws-sdk-go-v2/aws package, and github.com/aws/aws-sdk-go-v2/config module.

Error Handling

The github.com/aws/aws-sdk-go-v2/aws/awserr package was removed as a part of the SDK error handling refactor. The SDK now uses typed errors built around Go v1.13's errors.As and errors.Unwrap features. All SDK error types that wrap other errors implement the Unwrap method. Generic v2 preview SDK errors created with fmt.Errorf use %w to wrap the underlying error.

The SDK API clients now include generated public error types for errors modeled for an API. The SDK will automatically deserialize the error response from the API into the appropriate error type. Your application should use errors.As to check if the returned error matches one it is interested in. Your application can also use the generic interface smithy.APIError to test if the API client's operation method returned an API error, but not check against a specific error.

API client errors returned to the caller will use error wrapping to layer the error values. This allows underlying error types to be specific to their use case, and the SDK's more generic error types to wrap the underlying error.

For example, if an Amazon DynamoDB Scan operation call cannot find the TableName requested, the error returned will contain dynamodb.ResourceNotFoundException. The SDK will return this error value wrapped in a couple layers, with each layer adding additional contextual information such as ResponseError for AWS HTTP response error metadata , and smithy.OperationError for API operation call metadata.

result, err := client.Scan(context.TODO(), params)
if err != nil {
    // To get a specific API error
    var notFoundErr *types.ResourceNotFoundException
    if errors.As(err, &notFoundErr) {
        log.Printf("scan failed because the table was not found, %v",
            notFoundErr.ErrorMessage())
    }

    // To get any API error
    var apiErr smithy.APIError
    if errors.As(err, &apiErr) {
        log.Printf("scan failed because of an API error, Code: %v, Message: %v",
            apiErr.ErrorCode(), apiErr.ErrorMessage())
    }

    // To get the AWS response metadata, such as RequestID
    var respErr *awshttp.ResponseError // Using import alias "awshttp" for package github.com/aws/aws-sdk-go-v2/aws/transport/http
    if errors.As(err, &respErr) {
        log.Printf("scan failed with HTTP status code %v, Request ID %v and error %v",
            respErr.HTTPStatusCode(), respErr.ServiceRequestID(), respErr)
    }

    return err
}

Logging an error value will include information from each wrapped error. For example, the following is a mock error logged for a Scan operation call that failed because the table was not found.

2020/10/15 16:03:37 operation error DynamoDB: Scan, https response error StatusCode: 400, RequestID: ABCREQUESTID123, ResourceNotFoundException: Requested resource not found

Endpoints

The github.com/aws/aws-sdk-go-v2/aws/endpoints has been removed from the SDK, along with all exported endpoint definitions and iteration behavior. Each generated API client now includes its own endpoint definition internally to the module.

API clients can optionally be configured with a generic aws.EndpointResolver via the aws.Config.EndpointResolver. If the API client is not configured with a custom endpoint resolver it will defer to the endpoint resolver the client module was generated with.